Add row-level geo distance check and fix documentation examples - #1510

All committers have signed the CLA.

All commits in PR should be signed ('git commit -S ...'). See https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

Thanks for the review — all three addressed in 3ce2ddd6.

GeoJSON in supported formats

Good catch. The docstring listed the try_to_geometry formats (WKT, WKB, EWKT, EWKB) that I'd
copied from the sibling relationship checks, but this check parses with try_to_geography, which
also accepts GeoJSON. Updated in three places: the docstring, the reference_geometry argument
description, and the row-level checks table in quality_checks.mdx.

Missing convert_column=False test

Added two integration tests covering the native GEOGRAPHY path — one pass case, one violation:

def test_is_geo_within_distance_native_geography_violation(skip_if_runtime_not_geo_compatible, spark):
    """A native GEOGRAPHY value outside the radius is flagged, with the value rendered via st_astext."""
    point = "POINT(5.05 52.37)"
    test_df = spark.createDataFrame([[point]], _GEO_SCHEMA).select(
        F.call_function("try_to_geography", F.col("geom")).alias("geom")
    )
    condition = is_geo_within_distance("geom", F.call_function("try_to_geography", F.lit(_POINT_INSIDE)), 1000)
    ...

They build the column with try_to_geography in a select and then leave both convert flags at
their defaults, so the check receives a genuinely GEOGRAPHY-typed column. The violation case also
exercises the st_astext rendering branch, which is only reachable on that path — with
convert_column=True the message renders the raw input instead, since st_astext returns NULL for
exactly the unparseable values the invalid-geography message is about.

I assert on the condition column alone rather than also selecting geom, since a GEOGRAPHY-typed
column can't be compared against a string schema.

One thing I noticed while writing those

No test in the repo currently builds a native GEOGRAPHY column. Every is_geo_* check defaults to
convert_column=False, but all existing tests pass True, so the default path is untested across
the geo module rather than just here. Might be worth a companion issue to #1513 — happy to open one
if useful.

Thanks for opening #1513.

Pushed eeb4f887, which addresses the second round of comments and, more importantly, reworks the core of the check after verifying it against a live serverless workspace.

• The original design measured with st_distance on GEOGRAPHY. On this runtime st_distance, st_distancesphere and st_distancespheroid all reject GEOGRAPHY (DATATYPE_MISMATCH), and st_distance on GEOMETRY is planar — it returned 0.15 for two lon/lat points 10 km apart, i.e. degrees. The check now parses with try_to_geometry like the other is_geo_* checks and measures with st_distancespheroid, which returns meters on the WGS 84 ellipsoid (10,216.6 m / 68.1 m for the test points).
• st_distancespheroid is points-only and raises at runtime on any other geometry type, and on mismatched SRIDs (try_to_geometry assigns SRID 0 to WKT/WKB but 4326 to EWKT/GeoJSON). Both are guarded: a non-point column value or reference is reported instead of raising, and both operands are stamped SRID 4326 before measuring — 0 is treated as WGS 84, 4326 used as is, and any other SRID is reported rather than silently misread as degrees.
• An empty reference is reported on every row (it silently disabled the check), and a null reference column now leaves the row unmeasurable and skipped, matching the null semantics of the sibling checks.

Every behaviour above has an integration test that passes on the live workspace: the full test_row_checks_geo.py (75 tests, 20 for this check), the class-based and YAML all-geo tests, and the Studio seed tests.

@ghanse thanks for the two rounds of review — all five of your comments are addressed in eeb4f887, with a reply on each thread:

• GeoJSON added to the documented formats (and the SRID mismatch that mixing it with WKT would have caused is handled).
• convert_column=False now has integration coverage on the native GEOMETRY path.
• Too-far values render via st_astext, so WKB shows as WKT; unparseable binary input renders as hex.
• math.isfinite overflow is caught and raises InvalidParameterError.

One thing worth your attention beyond the comments: verifying against a live serverless workspace (DBR 19.6, so not a runtime-age issue) showed the original st_distance-on-GEOGRAPHY design couldn't work — the runtime's own DESCRIBE FUNCTION defines st_distance as 2D Cartesian over GEOMETRY, and no Databricks distance function accepts GEOGRAPHY. The check is now built on st_distancespheroid with point-type and SRID guards; every function it uses is documented for DBR 17.1+, so the declared minimum still holds. The PR description has the details, and the full geo integration file passes live (75 tests, 20 for this check).

Could you take another look when you have a moment?

@mwojtyczka thanks for the review — all five findings are addressed in eeb4f887, with a reply on each thread:

• Binary WKB rendering: unparseable binary now renders as hex; parsed values go through st_astext. On the live workspace the raw cast was worse than mojibake — it crashed result collection — so this was a real fix, not cosmetic.
• String distance validation: numeric strings are now held to the same rule as numeric literals, so "-100" and -100 behave alike.
• Operand-prep duplication: extracted into _prepare_geo_operands, shared with _has_topological_relationship_precise.
• F.expr / is_sql_query_safe: left as is, with evidence on the thread — F.expr can't execute statements, and the one thing it can do (scalar subqueries) is_sql_query_safe permits anyway. I've proposed a subquery guard in get_limit_expr as a follow-up so all limit-taking checks benefit consistently.
• Duplicated subexpressions: left as is; reasoning on the thread.

The check itself was also reworked after live verification showed the st_distance/GEOGRAPHY design didn't run on serverless — it's now st_distancespheroid over GEOMETRY with point-type and SRID guards, all covered by integration tests that pass live. Details in the updated PR description.

Would you be able to re-review?